破折号|末尾_GitLabAPI的使用教程

篇首语：本文由编程笔记#小编为大家整理，主要介绍了GitLab API 的使用教程相关的知识，希望对你有一定的参考价值。

GitLab 作为一个开源、强大的分布式版本控制系统&＃xff0c;已经成为互联网公司、软件开发公司的主流版本管理工具。使用过 GitLab 的都知道&＃xff0c;想要提交一段代码&＃xff0c;可以通过 git push 提交到远程仓库&＃xff0c;也可以直接在 GitLab 平台上修改提交。然而上述两种提交方式都是人工提交代码&＃xff0c;需要手动登录 GitLab 或者在第一次 commit 的时候提供 GitLab 帐号和密码。
那么&＃xff0c;假设有这么一个需求场景&＃xff1a;我们开发了一个效率平台&＃xff0c;可以自动拉分支、自动提交代码到远程仓库。这个需求该如何实现&＃xff1f;其实很简单&＃xff0c;GitLab 提供了一套完整的 API&＃xff0c;让第三方平台可以通过 API 自动创建帐号、自动提交代码、自动拉分支&＃xff0c;等等。API 涉及到的功能非常全面&＃xff0c;覆盖了分支、tag、代码提交、用户、群组、项目等&＃xff0c;基本上人工可以做的所有操作&＃xff0c;都可以通过 API 自动实现。

GitLab API 的使用可以参考你所使用的 GitLab 服务上的帮助文档。也可以参考 GitLab API 官网文档。
所有 API 请求都需要身份验证。您需要 private_token 通过 URL 或标头传递参数。如果作为标头传递&＃xff0c;标头名称必须是“PRIVATE-TOKEN”&＃xff08;大写并用破折号代替下划线&＃xff09;。您可以在个人资料中找到或重置您的私人令牌。
登录您的 GitLab 账号&＃xff0c;在左侧栏中选定【Profile Settings】&＃xff0c;再在左侧栏中选定【Account】&＃xff0c;如下图所示&＃xff1a;

如果未提供或提供无效&＃xff0c;private_token 则将返回错误消息&＃xff0c;状态码为 401&＃xff1a;


"message": "401 Unauthorized"



API 请求应以 API 的参数和 API 的版本为前缀。API 版本在 lib/api.rb 定义&＃xff0c;例如&＃xff0c;v4 API 的前缀就是/api/v4。
有效 API 请求示例&＃xff1a;

GET http://gitlab.example.com/api/v4/projects?private_token&＃61;<your_access_token>


使用 curl 和通过标头身份验证的有效 API 请求示例&＃xff1a;

curl --header "PRIVATE-TOKEN: " "http://gitlab.example.com/api/v4/projects"


这两个例子分别列举了 token 作为参数&＃xff0c;和作为 Header 的使用方法。在我们的程序中&＃xff0c;我们只需要选择一种自己方便的方式就可以了。
API 使用 JSON 来序列化数据。您无需在 API URL 的末尾指定.json。

3.1 获取 Projects 数据

http://gitlab.example.com/api/v4/projects/<project_id>/repository/branches?private_token&＃61;<your_access_token>


通过官方文档的说明&＃xff0c;如果要获取一个工程的分支数据&＃xff0c;除了 private_token 参数必填之外&＃xff0c;还需要知道这个工程的 project_id&＃xff0c;但从 GitLab 操作界面上并没有工程 id 查看的入口。
所以需要获取到所有 projects 的数据&＃xff0c;然后得到某个 project 的所有参数数据。
把 URL 域名参数和 Token 参数替换成自己的&＃xff0c;用 Linux 命令在终端测试获取下数据&＃xff1a;

curl --header "PRIVATE-TOKEN:" "http://gitlab.example.com/api/v4/projects"


执行之后获取到的数据是默认前20条&＃xff08;默认一个页面20条数据&＃xff09;&＃xff0c;JSON 数据结构如下&＃xff0c;可以看到里面的 id 字段就是请求分支数据需要的 id 参数。

[

"id": 1234,
"description": null,
"name": "Diaspora Client",
"name_with_namespace": "Diaspora / Diaspora Client",
"path": "diaspora-client",
"path_with_namespace": "diaspora/diaspora-client",
"created_at": "2022-09-30T13:46:02Z",
"default_branch": "main",
"tag_list": [
"example",
"disapora client"
],
"topics": [
"example",
"disapora client"
],
"ssh_url_to_repo": "git&＃64;gitlab.example.com:diaspora/diaspora-client.git",
"http_url_to_repo": "https://gitlab.example.com/diaspora/diaspora-client.git",
"web_url": "https://gitlab.example.com/diaspora/diaspora-client",
"readme_url": "https://gitlab.example.com/diaspora/diaspora-client/blob/master/README.md",
"avatar_url": "https://gitlab.example.com/uploads/project/avatar/4/uploads/avatar.png",
"forks_count": 0,
"star_count": 0,
"last_activity_at": "2022-09-30T13:46:02Z",
"namespace":
"id": 2,
"name": "Diaspora",
"path": "diaspora",
"kind": "group",
"full_path": "diaspora",
"parent_id": null,
"avatar_url": null,
"web_url": "https://gitlab.example.com/diaspora"

,

...

]


3.2 获取指定 Project 数据

如果 GitLab 上有几百个工程&＃xff0c;总不能把所有的都获取下来再去过滤吧&＃xff0c;通过查看 API 文档可以用 search 参数根据 project 名称去搜索想要获取的 project 数据&＃xff0c;比如这边要查找 test 项目的数据。示例请求&＃xff1a;

curl --header "PRIVATE-TOKEN: " "https://gitlab.example.com/api/v4/projects?search&＃61;test"


通过上面这条命令就可以获取到项目名包含 test 的前20条数据&＃xff08;官网文档描述默认20&＃xff0c;最大100&＃xff0c;可通过 per_page 参数设置&＃xff09;。

3.3 获取 branches 数据

通过前面的步骤获取到 test 项目的数据之后&＃xff0c;知道这个project的 id 值&＃xff0c;就可以接着通过 id 参数来获取这个 project 的所有分支数据。示例请求&＃xff1a;

curl --header "PRIVATE-TOKEN:" "http://gitlab.xxxxxxx.com/api/v4/projects//repository/branches"


示例响应&＃xff1a;

[

"name": "main",
"merged": false,
"protected": true,
"default": true,
"developers_can_push": false,
"developers_can_merge": false,
"can_push": true,
"web_url": "https://gitlab.example.com/my-group/my-project/-/tree/main",
"commit":
"author_email": "john&＃64;example.com",
"author_name": "John Smith",
"authored_date": "2022-06-27T05:51:39-07:00",
"committed_date": "2022-06-28T03:44:20-07:00",
"committer_email": "john&＃64;example.com",
"committer_name": "John Smith",
"id": "7b5c3cc8be40ee161ae89a06bba6229da1032a0c",
"short_id": "7b5c3cc",
"title": "add projects API",
"message": "add projects API",
"parent_ids": [
"4ad91d3c1144c406e50c7b33bae684bd6837faf8"
]

,
...
]


3.4 获取指定 branche 数据

上面是获取这个 project 的所有分支数据&＃xff0c;如果要获取指定分支的数据&＃xff1a;

GET /projects/:id/repository/branches/:branch


比如获取 master 分支的数据&＃xff0c;示例请求&＃xff1a;

curl --header "PRIVATE-TOKEN: " "https://gitlab.example.com/api/v4/projects//repository/branches/master"


示例响应&＃xff1a;


"name": "master",
"merged": false,
"protected": true,
"default": true,
"developers_can_push": false,
"developers_can_merge": false,
"can_push": true,
"web_url": "https://gitlab.example.com/my-group/my-project/-/tree/main",
"commit":
"author_email": "john&＃64;example.com",
"author_name": "John Smith",
"authored_date": "2022-06-27T05:51:39-07:00",
"committed_date": "2022-06-28T03:44:20-07:00",
"committer_email": "john&＃64;example.com",
"committer_name": "John Smith",
"id": "7b5c3cc8be40ee161ae89a06bba6229da1032a0c",
"short_id": "7b5c3cc",
"title": "add projects API",
"message": "add projects API",
"parent_ids": [
"4ad91d3c1144c406e50c7b33bae684bd6837faf8"
]




3.5 获取仓库提交列表

获取项目中的仓库提交列表&＃xff1a;

GET /projects/:id/repository/commits


示例请求&＃xff1a;

curl --header "PRIVATE-TOKEN: " "https://gitlab.example.com/api/v4/projects//repository/commits"


示例响应&＃xff1a;

[

"id": "ed899a2f4b50b4370feeea94676502b42383c746",
"short_id": "ed899a2f4b5",
"title": "Replace sanitize with escape once",
"author_name": "Example User",
"author_email": "user&＃64;example.com",
"authored_date": "2022-09-20T11:50:22.001&＃43;00:00",
"committer_name": "Administrator",
"committer_email": "admin&＃64;example.com",
"committed_date": "2022-09-20T11:50:22.001&＃43;00:00",
"created_at": "2022-09-20T11:50:22.001&＃43;00:00",
"message": "Replace sanitize with escape once",
"parent_ids": [
"6104942438c14ec7bd21c6cd5bd995272b3faff6"
],
"web_url": "https://gitlab.example.com/thedude/gitlab-foss/-/commit/ed899a2f4b50b4370feeea94676502b42383c746"
,

"id": "6104942438c14ec7bd21c6cd5bd995272b3faff6",
"short_id": "6104942438c",
"title": "Sanitize for network graph",
"author_name": "randx",
"author_email": "user&＃64;example.com",
"committer_name": "ExampleName",
"committer_email": "user&＃64;example.com",
"created_at": "2022-09-20T09:06:12.201&＃43;00:00",
"message": "Sanitize for network graph",
"parent_ids": [
"ae1d9fb46aa2b07ee9836d49862ec4e2c46fbbba"
],
"web_url": "https://gitlab.example.com/thedude/gitlab-foss/-/commit/ed899a2f4b50b4370feeea94676502b42383c746"

]